All committers have signed the CLA.

Hi @Steffen911 Please see my initial implementation of the separation. Its a lot and I'm happy to iterate on it. The biggest thing I tried to achieve is to keep as much build-time auto-generation as possible.

Fern itself is not very customizeable, so I started from an OpenAPI document, which can be generated from fern. There is very little code actually checked into version control - most of the power comes from the fact it is generated at build time.

Happy to answer any questions you may have.

You might think that 491 file changes is a lot, but more than half of that is simply moving what was there (generated by fern) into a subdirectory so it can be preserved.

Thought I would mention this too - there are Untyped Map-Like Fields in the Langfuse OpenAPI Spec. I'll open a new issue for this too.

Problem

The Langfuse OpenAPI spec (openapi.yml) has 28 fields across 18 schemas that represent JSON objects (key-value maps) but lack type: object and additionalProperties declarations. These fields have only a description and optionally nullable: true, with no type information.

In the OpenAPI 3.0 specification, a property with no type is treated as "any type" (AnyType). Code generators for strongly-typed languages map this to the language's top-level type — for example, Object in Java, any in TypeScript, or interface{} in Go — instead of a map/dictionary type. This degrades the developer experience because consumers must manually cast these values.

The spec already correctly types the same fields in other schemas (see Correctly Typed Fields below), making this an internal inconsistency rather than a design choice.

How We Identified Which Fields Should Be Typed

We used four criteria to determine which untyped fields should have type: object + additionalProperties: true added:

1. Internal Consistency Within the Spec

The same field name is correctly typed in some schemas but untyped in others. For example:

If the field is typed as type: object with additionalProperties in one schema, it should be typed the same way everywhere it appears.

2. Langfuse Documentation

The Langfuse documentation explicitly describes these fields as object/dictionary types:

• metadata: Documented as Record<string, unknown>. The v2→v3 migration guide states: "Only the Record type is supported within our UI and endpoints to perform queries and filter events." Non-object values sent as metadata are coerced into objects (e.g., "test" becomes { "metadata": "test" }).
• modelParameters: Documented as a string-keyed map ({ "property1": "string", "property2": "string" }). The UI renders it using Object.entries(), confirming it is always an object.
• config (on prompts): Documented as a freeform JSON dictionary. Accessed via dictionary methods in SDKs (cfg.get("model") in Python, cfg.model in JS/TS).

3. Semantic Analysis

Some fields are structurally always JSON objects by nature:

• inputSchema / expectedOutputSchema: These hold JSON Schema definitions, which are always JSON objects per the JSON Schema specification.
• tokenizerConfig: A configuration map for tokenizer settings — inherently key-value.
• lastConfig (in PromptMeta): The last-used prompt configuration, same semantics as config.

4. Exclusion Criteria — Fields That Should Remain Untyped

We explicitly excluded fields that can legitimately be any JSON value:

• input / output / expectedOutput: The Langfuse API documentation states these "Can be any JSON" — strings, numbers, arrays, or objects are all valid. Typing these as object would be incorrect.
• error (in IngestionError): Error payloads can be structured in various ways.
• log (in SDKLogBody): SDK debug payloads can be any JSON value.

Correctly Typed Fields (8)

These fields already have proper type: object + additionalProperties declarations and serve as the pattern that should be applied to the missing fields:

Fields Missing Type Definitions (28)

These fields should have type: object and additionalProperties: true added:

metadata (19 fields)

modelParameters (2 fields)

Note: The write-side schemas (CreateGenerationBody, UpdateGenerationBody, ObservationBody) already correctly type modelParameters as type: object with additionalProperties: { $ref: MapValue }.

config (3 fields)

Note: LlmConnection.config and UpsertLlmConnectionRequest.config already correctly use type: object with additionalProperties: true.

tokenizerConfig (2 fields)

inputSchema / expectedOutputSchema (4 fields)

lastConfig (1 field)

Cascading Impact via Schema Composition (30 schemas)

The 28 untyped fields cascade into 30 additional composed schemas via oneOf, allOf, and anyOf. Fixing the base schemas will automatically fix all of these:

Fields Correctly Left Untyped (18)

These fields are intentionally untyped because they can be any JSON value (string, number, array, object, or null). No changes needed:

Suggested Fix

For each of the 28 fields listed above, add type: object and additionalProperties: true to the property definition. For example, change:

metadata:
  nullable: true
  description: Additional metadata of the observation

to:

metadata:
  type: object
  additionalProperties: true
  nullable: true
  description: Additional metadata of the observation

And for the empty-definition case (BasePrompt.config: {}), change to:

config:
  type: object
  additionalProperties: true

langfuse-java-client -- Reference HTTP client built on java.net.http.HttpClient with dual Jackson 2/3 support, request/response logging with sensitive header masking, and automatic HTTP/1.1 fallback for plain HTTP connections.

IMHO, as you are already touching this, you should introduce an HTTP abstraction as done in LangChain4j which allows for the different HTTP clients.
This will make things for you (us?) much easier in the future with Quarkus

So theoretically I would be able to plug in a Jakarta REST Client?

langfuse-java-client -- Reference HTTP client built on java.net.http.HttpClient with dual Jackson 2/3 support, request/response logging with sensitive header masking, and automatic HTTP/1.1 fallback for plain HTTP connections.

IMHO, as you are already touching this, you should introduce an HTTP abstraction as done in LangChain4j which allows for the different HTTP clients.
This will make things for you (us?) much easier in the future with Quarkus

That's exactly what's being done here (and was the whole purpose of this PR). There are now 2 modules - an API and a client. They're completely decoupled.

So theoretically I would be able to plug in a Jakarta REST Client?

See the quarkus-langfuse extension. That's exactly what it does. For now the quarkus-langfuse extension has a copy of what this pr is doing, but that will get swapped out once this is merged and released

Wonderful!